fix(schemas): brain-spec used the wrong ID namespace; add a cross-schema check - #12

What this PR does

brain-spec.schema.yaml, which I added in #9, declares trust_signature.stage as T01–T04 while every other file in this repo uses aux.T01–aux.T04. A spec passing one schema would fail the other, and nothing here would have noticed until someone wrote one.

That is precisely the ID fork #9's own description warned about, and I let it through. It was caught by a validator someone else wrote and pointed at this repo — which is the argument for having one.

Changes

• schemas/brain-spec.schema.yaml — stage enum moved into the aux. namespace.
• schemas/validate.py — cross-reference checks, wired into CI as a new step.

yamllint proves each file is well-formed. This proves the files agree with each other: every gap resolves to a real heuristic and a real trust stage, every consequence-cap heat band to a real autonomy level, and enums duplicated across schemas stay in step.

On current main it fails, naming the mismatch:

FAIL brain-spec trust_signature.stage enum ['T01', 'T02', 'T03', 'T04']
     does not match trust-architecture.yaml ['aux.T01', 'aux.T02', 'aux.T03', 'aux.T04']

With the fix:

ok   parsed 8 YAML file(s)
ok   brain-spec.schema.yaml is a valid JSON Schema (draft 2020-12)
ok   gaps -> heuristics resolve (12/12 gaps carry a heuristic ref, 10 heuristics)
ok   gaps -> trust stages resolve (12/12 gaps carry one)
ok   heat bands -> autonomy levels resolve (5 bands)
ok   2 duplicated enum(s) match trust-architecture (stages)
skip gaps -> families (no `families` key in trust-gap-taxonomy.yaml)
skip families -> trust stages (one side absent)
skip patterns -> heuristics and gaps (no `patterns` key in trust-contract.yaml)
PASSED

Why the skips are the interesting part

A check whose source key is absent reports skip with the reason, never ok. trust-gap-taxonomy.yaml carries no families key and trust-contract.yaml no patterns key, so those cross-references cannot run yet — and the tool says so rather than claiming a comparison it never made.

That distinction is not hypothetical. An earlier draft of this validator reported ok for "gaps → heuristics resolve" after zero comparisons, because it looked for a key named heuristic while this repo uses heuristic_ref. A validator that reports success for a check it never ran is worse than no validator, and this one is now built not to.

The three skips also become useful signal: they mark exactly where trust-gap-taxonomy.yaml and trust-contract.yaml are thinner than the versions discussed in #9's out-of-scope list. Enrich either file and the checks switch themselves on.

Linked Issue

None required — no IDs introduced, and aux.T01–aux.T04 already exist. This aligns a file that had drifted out of the established namespace, so it is a correction rather than a vocabulary change.

Type

• New pattern
• New gap
• Teardown
• Framework edit
• Schema fix
• Doc fix / typo / link
• Other

Contribution bar — checklist

• I've read CONTRIBUTING.md.
• If this introduces or renames an ID, I opened a debate Issue first. — no new IDs; a file is brought into the existing namespace.
• If this adds a pattern, it has a diagram, a runnable example, and an anti-pattern. — n/a.
• If this adds a gap, it has a reproducible scenario and references a heuristic or trust stage. — n/a.
• CI passes (schema validation, link check). — verified locally: the new check passes, 34/34 aux-audit tests, yamllint clean, check:schemas clean, check-coverage.py 12/12, links resolve.
• No emoji in code or schemas.
• Short sentences. Named things over adjectives.

Out of scope

The agent-spec v1 migration package — v1 schema, migrate-v0-to-v1.py, MIGRATION.md. Held for #10, with one finding worth recording there: the swap costs about four lines in aux-audit (spec.ts reads the schema by filename, sync-schemas.mjs lists it, two test references), and 34/34 pass after repointing them at agent-spec.v0.yaml. Cheaper than #10 estimates.

But a spec written to v1 and fed to the shipped CLI is rejected with four misleading errors — `autonomy` is required, for fields v1 deliberately removed. So publishing v1 under the canonical filename while the CLI still reads v0 replaces an inconsistent document with a broken tool. Options and a proposed shim go in #10.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MhpqWEvwKp7NrmJfdXYq4M

Generated by Claude Code